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Your new xForth system 


Copy your disc before doing anything else. 

The upgrade from xForth 1 to xForth 2 consists of this 
documentation as described in the contents table, and in 
particular containing a glossary update, together with a disc 
or discs containing the following files: 


XFORTH.COM 


This is the normal xForth system. Call CONFIG 
when you first use it. 


XF808014.COM 


FORTH.BLK 


If you have an 8080 processor or your operating 
system is CPMl.4 or CDOS, or you have trouble 
as described in "Trouble" below, use this file 
instead of XFORTH.COM. You will lose the 
ability to access user areas in CP/M and will 
be restricted to 256Ps files. Not supplied with 
Torch systems. 

The usual FORTH.BLK file with some updates and 
with blocks 30 onward removed. 


The screen editor with some minor updates. 
TORCHSEE.BLK for Torch systems has some 
slightly different facilities. 


SEEDATA.BLK 


CONFIG.BLK 


BINDINGS.BLK 


Sets up editor keys from a file instead of from 
keyboard. TSEEDATA.BLK differs slightly. 

Called by CONFIG, minor changes from version 1. 
TORCONF.BLK for Torch differs slightly. 

Changes editor keys. Same as old version. 


NEWSIEVE.BLK Faster Eratosthenes sieve. 


SPOOL.BLK 


A file listing background task. 


DELAY.BLK 


Multitasking clock words. Needs edits to adapt 
to your system. 


TDELAY.BLK DELAY.BLK configured for Torch. 


BUFFER.BLK 


Print buffer using multitasking, 
to adapt to your system. 


Needs edits 
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TBUFPER.BLK 


BUFFER.BLK configured for Torch. 


WINDOWS.BLK 

TASKDEMO.BLK 
NARRATE.BLK 


Simple multitasking windowing demonstration for 
orch, needs adaptation to other systems. 

Demonstration of WINDOWS.BLK, for Torch only. 

Modified file for turtle graphics owners. See 
coraments on changes to xForth optional 

r'l ir rik n ^ 


SAVE.BLK 


with no SAVE command 
Turbodos, you can load this file then 
SAVE-AS MYXFORTH.COM after configuration. 


e.g. 

type 


Other files 
as in xForth 1; 
that certain 
"Changes needed 


are not supplied since they are mostly the same 
you can copy them to your working disc. Note 
optional packages need slight changes: see 
to xPorth optional packages'** 



B; DIR 


B:DIR? 


A>B:DIR 


B: 

XFORTH 

COM 

B: 

SEE 

BLK 

B: 

NEWSIEVE 

BLK 

B: 

SAVE 

BLK 

B: 

TASKDEMO 

BLK 

B: 

COPY 

BLK 

B: 

QUEENS 

BLK 

B: 

OLDSTUFF 

BLK 

B: 

DEBUG 

BLK 

B; 

SEARCH 

BLK 

B: 

EASTER 

BLK 

B> 




: LIFE BLK 

: SEEDATA BLK 
: SPOOL BLK 
: WINDOWS BLK 
: NARRATE BLK 
: TTY-RUB BLK 
: SIEVE BLK 
: SEQ-IO BLK 
; DUMP BLK 

: CRYPT BLK 
: HAMURABI BLK 


NEW-LOOP 

BLK 

CONFIG 

BLK 

TDELAY 

BLK 

DELAY 

BLK 

QERROR 

BLK 

FIG-ED 

BLK 

RANDOM 

BLK 

VMOVE 

BLK 

QUICK 

BLK 

TO-SOLN 

BLK 

EXPONENT 

BLK 


FORTH BLK 
BINDINGS BLK 
BUFFER BLK 
TBUFFER BLK 
XF808014 COM 
JACK BLK 
FRACTION BLK 
ASSEMBLE BLK 
VLIST BLK 
HILEV-TO BLK 
MODULES BLK 


DIR 


B: 

BUILD 

BLK : 

XFCODE80 

TXT 

3: 

METASYS 

TXT : 

XFUPPER 

BLK 

B: 

CPM-DISC 

BLK ; 

CPM-EQUT 

BLK 

B: 

B> 

-READ 

ME- : 

ASSEMBLE 

BLK 


XFHILSV 

TXT 

XFTASK 

TXT 

SYSEQUTS 

BLK 

CPM-I/0 

BLK 

FLAGS 

BLK 

XFORTH 

COM 

VMOVE 

BLK 

FORTH 

BLK 




A> 

A > y t tf ];■ e r e P r e a d. m e C? 


souv'ce code dice 


xForth 2 


For your convenience, tlx is disc contains a trxnicated copy of 
FORTH,BLK and a version of XFORTH.COM that is pre-configured' <tc 
a .ut.C Vr-52 (verminai). This tneaxis the disc, contxiins all thi. 
files needed to rxin BUILB.BI..K ai'sd build a system thot is read' 
for SYS8EN. 

To biiild a new kernel system xn the file KERNEL-COM, simply loac 
tlxe file BUILD.BLK and aviswer Y to tFxe questions about parameter 
sett.xnqs„ (If you answer N to the question about DEBUfj xForth 
w.ill go away for some time, with only min.imal comments, before 
.i.t piT'odi.ices tFxe vixi-w system.) Not ail tixe files nxi'eded toy’ tlii 
various options are supplied? in particular, you must always 
leave 6Sk arxd f83 set to FALStE. Novr-Torcii users must leave 
Torch set to FALSE and Torch users must sxit it to TRUE,. 

Note t i x a t t Fx tt .TXT f i 1 e s a r 1 o a d xj d ( s 1 o w 1 y) b ij t F\ e s t a n xi a r d 
L0AB“FIL1::. „ I lxe se i \uen tia 1 .i/o pxic k a ge” s ' 1 oad wor d .is muc 
fxxster tixxiyx LOAD-FILE for .TXT f.iles bxit .it i>is.ists tFxat 
constructs all be ovj one line whicFx would mexin tFxe files Fxad ts 
edited. You could convert the .TXT files back to .BEK fxlxjr 
(addin q -•-> wFxere nexs-ded) if requirexi, using tFxe ’ uvtascii, ^ 
u t .t 1 i. t u i n t h e e q u e n t i. a 1 - i / o p a c k age. 


A>d 

Ext-enxiixai D:irectory ■v'ersio'n 3.,5 


{?READ .MEO 

2 k 

ASSFIMBLE. BEK 

9 k 

BUILD .BLK 

3 k 

CPM(?DIGC.BLK 

10k 

CPMOEQUT.BLK 

Ik 

CPMOKJO .BLK 

:li'. 

D .COM 

3 k 

FLAGS .BLK 

3 k 

FORTH .BLK 

8 k 

METASYS .TXT 

10k 

SYSEQUTB.BLK 

Ik 

OMOVE .BLK 

2 k 

XFC0DE80.TXT 

2 4 U 

XFHILEU .TXT 

2ek 

XFORTH .COM 

20k 

XFTASK .TXT 

7I< 

XF(.iFPER ..BLK 

13k 


D.xsk As Ih blocks 

.iT3vji\ j. 1/ Isiies, Usexj '--- l4VK, S pxicts-'' ooK 


I 20 






Additional notes 


SYSGEN 

;:Fort‘\ is supplied only as the file XhO!'< TH. C;OH so if you warrt 
tk:i generate a private system by modifying hi. qcI: ] and calling 
V t) G ii IM, y o u h a V e t o r* e iin o v f? all the w o r d s ci e t i e d s i rt c t h e 

d i:? i 1 V e r d b 1 o t: 1: 1 w a s 1 Oi < d e d . 1 u d o ri a ^ p r o c e e d ‘h; f a 1 i (3 s s 

X l--‘it(JHI fk:.L.. AC E 1.)- E V CR 
XBIt;NAi\i Ri:y (s.i bngn) 

F t: NCE -BEiiJW CGL 1) FFiF'TV 

r’RiJ 1 F.i.’ f 

i d I t i SI V:> lIos'S i:.-nse the n eiiei nr ion vcu' .i. ab 1 e<:i ar v? ''isi'i 

t o e L l\ a ng i? i::! ^ e t hen r ve e ver' y t h i nt] li at need s t o b e 

r e i I i * .5 V s‘ d « i f y o " v s' r e ™- s- et o r li X !<. E o r* a i "i y t.!' 11 n q e i e ^ y n a ' .1 .L 

n c‘ e d t o M\ cd e s u r t li e y i'" rr s a i e t o cj« 
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(c) A.I.M. Research 


Kep 

YiFoimir i 


Setting started. 


To run nForth you need an B080, 0085 or zuu ^nici/oprocessor 
vwi th at least 2BK of ejemory, running the CP/p operating 
^stefn. You really need at least 32K to j/o anything 

Hdrthnhile. A VDU with cursor positioning abilil^ is a great 
hei^ but is not absolutely essentials Note that/ versions for 
Q0B&\and Z80 processors are different, and versons for CP/Hl-4 
and cH/li2«2 are different. If you have on^of the BQ*“Called 
’CP/M ^mpatiblt^' operating systems, you wi 1/1 probably find no 
problems\but we don’t guarantee it -- therms no such thing as 
1007. compatibility with a system like CP/MAhat isn’t properly 
defined an Where except by its own source/code. 

Before ycibi do anything else, the whole disc and put 

the original ai^y in a safe place.X Now fill out and return 
your licence agreement if you haven’t/done so already- 



The disc you h^e copied onto 
disc. Use CP/M’sprogram SYSGE! 
options, on some sys^^ms) to 
system on this disc, 
and Z80 versions of 
deleting the files you 
ZQO)« You are ready to 


11 be your initial working 
(or COPY with appropriate 
t a copy of your operating 
you been supplied with 

Forthj/you can make extra 
don/1 r/4ed (titles containing 
staXt. 


both 8080 
space by 
8080 or 


Put the working disc ir/ <X;ive A and type 

A>28KZ8(y oX A>2aK80e0 


to load up a basic sy* 
CP/M (i-e. xForth tak« 
by the CP/M system^ 


:em that w^l1 run under as little as 28K 
20K and CP/M takes 8K). The A> is typed 


xForth will 
will see 

/ 


sign on. 


Type 


carriage return and you 


^mpty 


Now type 


f q 1lowed 
quest i or 



CONFIG 


y a carriage return, and xForth wi1 
and answer session with you to set itself 



conduct a 
p f or your 


0 
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terminal an^ your number of disc drives. You might like to 
know that mosH: terminals have 80 columns and 24 rows, add do 
wrap long line^ (i.e. lines longer than SO characters/spi 11 
over to the n^xt line rather than having the rightmoj^t part 
lost altogether)\. / 

\ 

To allow the\ screen editor to work, xForth n4eds to know 
how to postion the cursor. If you have any a number of 
common cursor addre^sable terminals such as ADM^, Superbrain or 
Z19, the code is already written and you will tie able to choose 
the right code from a\inenu. If you don't a terminal that 
appears on the configuk^^ation menu or is compatible with one of 
the terminals appearing\there, you'll have to write a little 
cursor^ handler as explNained in the ^fipendix 'Altering your 
system . However, you cab use every^?fiing except th® screen 
editor right away, so dan’\ bother about this until you've got 
used to the basic system. 


After the question and 'ta^wer session, xForth will adjust 
itself to be able to use as mdth memory as passible in your 
Notice that aftei^ at^pting itself to your system, 
xForth tells you how many^P/M pages it occupies. Type BYE and 
then, when you are back CP/M,Vype 

^SAVE 65 XFO^H.CON 

where 65 is repla^d by however marty pages xForth just told 
you. From now on,/you merely need to\type 


A>XF0RTH 

to get goingy/unless you change your CP/I^system size, in which 
case? you should repeat: t:he above eteps* \ 
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Chapter 1 

Updates in xForth 2 


is 

you 


Don t be put off by the length of this document; much of 
a glossary containing a detailed description. To get going 
probably only need to know about the following: 


Multitasking; 


New file system facilities (mainly user numbers and DIR); 


New character input/output facilities 
input/output streams); 


(mainly enhanced 


Miscellaneous new features; 


Minor changes needed to assembler and floating point oark 
due to change to direct threaded code, and to debug ^ and 
turtle graphics packs due to changes to i/o system 
Also, the decompiler no longer works. 


rru is a summary of the most important features. 

Ihe detailed glossary should be consulted in cases of doubt 
and tor precise definitions. 


1.1 Multitasking 


t-u described in detail in the next chapter. Note here 
that uhe multitasking demonstration files may need to be set 
up tor your system before you try to load them. 


file system facilities 


The 
areas • 
end of 


filing system now knows about CP/M2 CP/M3 and CPN user 
If ^a user number is given in square brackets at the 
a tii.e name that user number will be used for the file. 


I zo 


3 
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e.g. 

LOAD-FILE random.txt[0] 

This is particularly useful for users with high capacity 
discs. If no user number is given the currently set operating 
system default user number is assumed. The new words setuser 
and getuser have been introduced to allow control over this. 

DIR now reads an ambiguous file specification with optional 
user number from the input stream, and lists on the currently 
selected output streams all files in the stated user eirea that 
match the specification. Note that no stack argument is used 
as in xForth 1. If the file specification is empty it is 
assumed to be *.* so that typing DIR and pressing return has 
the same effect as it has in the operatinq system. Some 
examples of calls are: 

DIR 

DIR *.BLK 
DIR f?g*.x[5] 

DIR c:[2] 

DIR b: 

DIR [15] 

DIR a:b?d.*[ll] 

The word $DIR takes a string argument and operates on it in 
the same way. 


LOAD-FILE now allows ordinary text files (prepared with any 
standard editor) to be read as if they were being typed from 
the keyboard. This is done by selecting input stream 2 which 
is connected to the file in question. Loads may be nested and 
files of type .BLK, which are treated as usual, may load and 
be loaded by text files. The sequential i/o package provides 
utilities to convert block files to and from ASCII files. 

Since the word WHERE is no longer so useful with text 
files, a variable 'echo' is provided. If it is set to TRUE, 
as in echo on', each line of the file being loaded is 
reflected to all currently selected outputs before being 
interpreted. Note that the usual rules about ( and { having 
to have matching ) and } on the same line in console input are 
relaxed for text files, but that defining words such as ; and 
VARIABLE must be followed on the same line by the word they 
are defining. 


I zn 


4 




xForth 2 (c) Alistair Mees 


1.3 New input/output facilit ie^ 


The input-output facilities are much shinier than before. 
They are now vectored in such a way that there may be 4 
distinct input streams and 4 distinct output streams, and any 
task may select any of them. 

The method is to use bits set in the user variable OUTPUTS 
(which all tasks have a private copy of) to select output 
streams, and bits set in the analogous user variable INPUTS to 
select input streams. Conventionally, the lowest order bits 
are the normal output and input so that setting INPUTS and 
OUTPUTS both to 1 gives normal operation. The next higher 
order bit in OUTPUTS corresponds to the printer and is toggled 
when control/p is typed. Thus to select the printer alone 
from within a program, set OUTPUTS to 2; to select both the 

printer and the vdu set it to 3, since EMIT sends its 
character to every stream that has its bit set. (Note, 
however, that KEY only asks for a character from the input 
stream with the lowest order bit set.) 

The next bit, corresponding to setting OUTPUTS or INPUTS to 
4, is reserved for file stream i/o though only a (slowish) 
version for input is provided in the standard system. It is 
used by LOAD-FILE to load ASCII files containing xForth 
programs. 

The next bits, corresponding to setting OUTPUTS or INPUTS 

to 8, are free for your own use. 

The actual streams cire defined by the execution vectors 

XEMIT and XKEY v/hich have room for 4 codes each instead of the 
1 each in xForth 1. On delivery, the codes for XEtllT ate 
EMITT, EMITP, DROP dind DROP. On delivery, the codes for XKEY 
are (KEY), EOF, getc and EOF where getc reads from a file. 
The intention is that you should always use EMIT in your 

programs, altering OUTPUTS and INPUTS to get the desired 
effect, and leaving use of EMITT and EMITP and so on to system 
words. 

Finally, "EMIT now interprets "M as a call to CR, 
interprets "L as a call to PAGE, ignores 'J, and expands tabs 
to a multiple of the constant tabsize which is normally 8 but 
may be changed on configuration, (5 is a good value foi- 
programming,) 
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1. 4 Miscellaneous changes. 


xForth 2 is somewhat faster than xForth 1 since it uses 
direct threaded code instead of indirect threaded code. This 
change was made because it paves the way for a code optimizer 
in future. The overall improvement in speed is about 15%; 
test it on SIEVE and on QUEENS. By the way, your disc 
includes a program NEWSIEVE which was written to do the Byte 
SIEVE benchmark properly in FORTH and so give a fairer 
comparison between Forth and other languages. It takes about 
43 seconds for 10 iterations in xForth 2 on a 4MH2 Z80 
machine. 

Note that a few changes are needed as a result of the move 
to direct threaded code. They are described in the next 
section. 

xForth 2 now sizes memory automatically so there is no need 
for the 2aKZ80 followed by CONFIG followed by SYSADAPT 
operation formerly needed. Just type XFORTH. You still need 
to run CONFIG to set up for your terminal. 

xForth 2 is about 2600 bytes larger than xForth 1.21, 
though because of the way free space is now measured (see 
DICTLIM) the amount shown on signon may not appear to cigree 
with this. 

Three new words have been added: 'on' 'off' and '0!'. They 
set a variable whose address is on the stack to TRUE, FALSE 
and 0. For example, you can say 'echo on' and 'echo off'. 

A number of other new words have been added, some of them 
from Forth 83. One example is >BODY which converts a code 
field address to a parameter field address, i.e. it is the 
opposite of CFA. Make sure that anywhere you w'ere using 24- to 
do this job you now use >BODY since the size of the code field 
is no longer 2 and is not guaranteed to have any fixed size. 

Two other new words from Forth 83 are SPAN and #TIB which 
hold the number of characters read by the last call to EXPECT, 
and the number of characters in the text input buffer. 

One new word, not from Forth 83, is +LIST which lists from 
a block number until the end of file is encountered. 

A number of words have been removed: an example is (LOOP) 
which is merely the code compiled by LOOP. It is hoped that 
those removed will not be missed: actually, we were glad to 


6 
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see the back of them, 
the glossary update. 


They are summarized at the beginning of 


example, 

rh? werT -le, 1“?® ^1“'' abandon 

i/okbulary. ^ ^ ^ shitted into the (EDITOR) 


arnument to uses a stack 

bottom of the nc-n P“'^ variable relative to the 

Dottom of the U&CiR variable area. Instead it keeps track of 

1 many user variables there are in the constant #UVARS. 


Iri_gjia!iaes_r^ ded to xForth optional packages 


The 

a Iready 
product 
cJirect 
xForth 
they wi 
of spec 


following changes need to be made to packages you have 

icfr^of^^ mainly concerned with 

of CODE sections and result from the change to 
tnreaded code which has changed the header structure of 
words. If you have written any CODE words yourself 
11 only need to be recompiled unless you have made use 
lai knowledge of the structure of word headers 


There are 
are concerned 
input output 


also a couple of changes to the DEBUG pack which 
With deletion of a definition and with the new 
facilities. 


packages wirn or since th< 
e..Sion .b the changes will have been made for you. 


with or since the upgrade to 


1.5.1 ASSEMBLE.BLK 


line 10 of block 3 of the assembler, 
CODE should now be 


the definition of 


; CODE ?EXEC CREATE SMUDGE -3 ALLOT 

[COMPILE] ASSEMBLER iCSP ; IMMEDIATE 


i.e. instead of 'HERE DELTA - -2 ALLOT 
A LLOT'. 


we simply have 




1.5.2 FP.BLK 


In line 11 of 
we now need 


the first block of the 


floating point pack. 


I so 


7 
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CREATE fppack HERE 4 + -3 ALLOT HEX 0C3 C. . 

DECIMAL - '-f » 

which puts a jump to HERE+4 in to the code field instead of 
merely cormna-ing in the address of HERE+4. 

'wriin block 2 of the floating point pack, replace 

lIND fppack @ with FIND fppack 1+ @' to compensate for the 
above change. 


1.5.3 TRIGS.BLK 


Owners of the turtle graphics package should remove the 
code definition for 'U2/' in the file TRIGS.BLK and replace 
all occurrences of it with '2/'. 


1.5.4 DEBUG.BLK 

The debug pack needs to have a couple of changes. Since 
the lethal word LIT is no longer present, line 12 of fhe first 
block of the debug pack, which redefines it to be safer, 
should be deleted. Also, because of the new input/output^ 
facilities the definition of 'wait' on block 4 of debug.blk 
doesn't work. Delete the definition of (last-key) and replace 
the definition of 'wait' with 

: wait KEY DUP INTRPT-KEY @ = 

IF XINTRPT @ EXECUTE ENDIF ; 

You can also check for hitting control/C if you like. The 
normal interrupt facilities during output are still there; all 
that this affects is the operation when pausing is turned on. 


1.5.5 NARRATE.BLK from Turtle graphics pack. 

A tricksy Forth definition was supplied with the turtle 
graphics demo, to let selected parts of Forth blocks be echoed 
while loading. Because of the changes to input/output 
facilities, a slightly different set of dirty tricks "is 
needed. Replace the file NARRATE.BLK from your original 
turtle demo with the new one on the upgrade disc. Ignore the 
revolting style and layout of this file! 


... Q .. 
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Chapter 2 

Multi-tasking in xPorth. 


In computer jargon, "multitasking" refers to a situation 
where a computer appears to be doing several different and 
possibly unrelated things ("tasks" or "processes") at the same 
time. Most computers, and nearly all microcomputers, do not 
leally do several things at once, but chop up all of their 
tasks into bits and do a bit of one, then a bit of the next, 
and so on. This requires great care if the tasks v/ant to 
communicate with one another successfully. 

xForth multitasking facilities are more powerful than those 
we know of in any other Forth. For most purposes they are 
easy to use; the instructions that follow describe them in 
general terms, and the example files and the updcite glossary 
give more details. 


An 

like 

holdx 

provi 

which 

both 

def in 

print 


obvious use for multitasking is to let slow peripherals 
printers be driven by special background tasks instead of 
ng up normal use of xForth. This can be done either by 
ding a print buffer or by making sura that any tasks 
talk to the printer are in the background. Examples of 
are supplied: for the second case, a word PRINT-FILE is 
ed which passes a file over to a background task for 
ing and does not need a large print buffer. 


Some of the other uses for multitasking range from simply 
showing a clock or calendar in a fixed part of the vdu screen, 
through displaying the current values of memory locations as a 
check during debugging, to timed control and data collection 
tasks. A sample windowing program is provided so you can see 
different tasks working at once. The only limitation is your 
imagination! 


2.1 S i mple multitasking. 


A "task" in xForth is a special sort of definition that 
*ooks like a colon definition except that it starts v;ith 
TASK:' instead with When first defined it does nothing. 
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but once it is started, it takes over control of the computer 
and retains control until it runs to completion, or it 
temporarily hands over control to another task, or it gets 
blocked until some event happens. What this means is that 
tasks in xPorth cooperate with one another, by not 
deliberately hanging on to the computer for long periods ot 
t ime. 


Diocfced until some 
tasks in xForth 


In the first case, where the task runs to completi 
control then passes to the next task in a queue which 
managed in such a way as to give all tasks a fair chance 
same happens in the second case, except that thp task 
reinserted at the tail of the queue. when ifs turn com^-c 
Will continue where it left off. The third case, waiting" 
an event, occurs when the task asks to be held up until’% 
particular time, or until it receives a signal from anot 
task saying, perhaps, that there is some data waiting to 
processed. 


task 


waiting 


) be held up until s( 
a signal from anot! 
ome data waiting to 


Here is an example of a task that sounds an alarm if the 
value of a variable gets outside a certain range. This sort 
of thing is useful for debugging, as you can run the watchdog 
task then start up whatever you are debugging. This will work 
as long as the word being debugged gives up control from time 


to time. As was mentioned above, 
uses for multitasking. 


this 


only 


many 


VARIABLE var 
0 CONSTANT minvar 


— Assumed to be used by some other task, 
9998 CONSTANT maxvar 


TASK; checkvar BEGIN var @ rainvar maxvar in-range'^ 

WHILE PAUSE 
REPEAT 

BELL 2 CRS . '• var = " var ? 2 CRS ; 

As you can see, this is just like a colon definition exceot 
that It starts with 'TASK;' instead with Nothing happens 

when you first define it but once you start it, with 

checkvar START 

it loops around, checking the value of 'var' on each pass. If 
the value is ok, checkvar calls the special word ' PAfTSE' whieh 
says "pass control to the next task that's waiting to go, but 
put site back in the queue so I get a chance to run again". 
Wnen it next runs it will restart v^here it left off, with the 
stacks and so on all intact- ^ ur 1 1 1 TTt TC» R m . .1. i t. 


will meet REPEAT which 


sends it back to BfiGlN and another time around. If the value 
i.j bad, it sounds the alaiin and then stops, because vou 
presumably want a chance to put things right. In this casn 
the tasks stopped because it reached the end of its definition 

but_ it could also have called QUIT from within the 

definition. 
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Now try typing in the above example and starting the task, 
and then define 

; changevar BEGIN 10001 RANDOM var ! PAUSE 7TERMINAL UNTIL ; 

and run 'changevar'. You can stop it by hitting any key, but 
if you don't then eventually it will set 'var” to 9999 or 
iOOOO and 'checkvar' will complain. The use of PAUSE in this 
example makes sure the user task (the one you're talking to 
normally) gives other tasks their chance to run. It would 
also have done so without special action on your part if it 
had called KEY which has a call to PAUSE in its definition. 

In fact, a possible definition of the keyboard reading part of 
KEY is u e - 

: (KEY) BEGIN 2TERMINAL NOT WHILE PAUSE REPEAT LAST-KEY ; 

Notice how the so-called 'busy waiting' loop 

: (KEY) BEGIN 7TERMINAL UNTIL LAST-KEY ; 

has been changed to give other tasks a chance if the present 
task is waiting for input. 

If that were all you had available to control when a task 
runs, you could still do quite a lot. Many large data 
monitoring and control applications have been written in this 
way, including, I understand, American Airlines' baggage 
handler, speed and depth monitoring on Missippi tugboat 
trains, and many others. However, if two tasks have to 
cooperate they must be written very carefully. The xForth 
task handler allows advanced control via delays, semaphores, 
counting semaphores, demons and monitors. Before studying 
them we have to think a little about the structure of a task. 


2_ User var ia bles ^tnd p rivate stacks. 


A task needs to be able to work largely independently of 
other tasks. To do so it needs its own stack and return stack 
(although so-called multitasking systems exist which try to do 
without this). It also needs some private variables so that 
J-t can, for example, change OUTPUTS to send its output 
somewhere without messing up other tasks. 

Such variables are traditionally called USER variables in 
forth. They are provided in xForth for each task, with a 
complete set being available for normal tasks and a limited 
set for small "background" tasks. When you type the name of a 
task it leaves the base of its user variable area on the stack 
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and this is used by other words to manipulate the task. 

When you define a task xForth sets aside an area of memory 
for user variables, with the stacks and, for normal tasks, a 
terminal input buffer and a small private dictionary area. 
This is initialized when a task starts up and is accessed only 
by the task itself. Tasks communicate via ordinary VARIABLES 
or via semaphores as we will see later. 


2.3 De l ays 


Delays are easiest to explain. Suppose you want a task 
that just does one thing at a fixed future time: maybe it 

opens a control valve, puts an appointment reminder on your 
vdu, or something quite different that you can no doubt think 
of yourself. You need a clock. If your computer has a 

built-in clock you will find out later how to tell xForth 

about it, but for now just load the file DELAY.BLK which 

simulates a clock by having a little task that just increments 
a variable every time it has its chance to run. (Torch users 
can load the file TDELAY.BLK which uses the BBC micro's clock 
correctly.) Now type 


5 seconds DELAYFOR 

and XForth will go dead for a while (which is unlikely to be 
very near 5 seconds unless you have a Torch or your computer 
is very similar to ours). What has happened is that the user 
task -- the one that talks to you and listens to your answer - 
was put on a delay list with a tag saying when it was to be 
restarted, and a clock monitor checked the list whenever its 
turn came to run; when the pseudo-timer said the time was 5 
seconds later than it was when you first typed DELAYFOR, the 
user task was allowed to continue. 

The reason for having a special clock monitor is that there 
may be many delayed tasks, but they do not all need to keep 
coming back to check the clock since the special clock monitor 
task can do so more efficiently. Indeed, it may be possible 
on some systems to make the clock monitor interrupt-driven, so 
it doesn't consume any time at all unless a task is due to be 
run. 

A more realistic use of DELAYFOR (and its friend 
DELAYUNTIL, which waits until the clock shows a certain time) 
is in a task such as 

TASK: readdata 

19 hours DELAYUNTIL 


12 
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initialize 

BEGIN meterl read meter2 read 

5 minutes 20 seconds D+ DELAYFOR 

AGAIN ; 

The words 'hours', 'minutes' and 'seconds' all take a single 
precision integer from the stack and scale it to a double 
precision number which is the correct number of clock ticks 
for your system. To combine them we use D+ as in the last 
example. Both DELAYUNTIL and DELAYFOR expect a double 
precision number of clock ticks on the stack, and you can 
generate it any way you like, not just with 'seconds' and so 
on. 


2.4 Semaphores, or how tasks communicate. 


Tasks communicate to some extent via public (non-USER) 
variables, but there are certain types of communication that 
are so common and so important that it is a good idea to 
provide special facilities. These facilities are concerned 
with event control. 

A good way to think about the way the delay words work is 
to say that words that call them are giving up control of the 
computer until a certain event occurs: in this case, a certain 
time shows on the clock. Other sorts of events can be handled 
too, via "semaphores" which are indicator lights that are red 
when an event hasn't happened or a facility is in use by 
someone else, and green when the event has happened or the 
facility is available for use. 


2.4.1 Two state semaphores, and demons. 

For example, suppose several tasks are sending output to 
the printer. We don't want their output to get tangled up so 
we make them obey the semaphores like traffic lights or 
railway signals. They use the word WAIT to look at the signal 
and hold off if required. We define a semaphore: 

SEMAPHORE printer 

which is an object with a variable and a queue. If the 
variable is nonzero, (typically 1) the light is green and we 
can go on; 

printer WAIT 

will decrement the variable and do nothing else. But assuming 
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the variable was 1, if 
then WAIT discovers the 
of the task, adding it 
WAIT. 


some other task calls 'printer WAIT' 
signal is red and suspends execution 
to the tail of the queue managed by 


When our first task is finished with the printer 
the world by saying ' 


it tells 


printer AVAILABLE 

which removes the first task from the queue (leaving the light 
at red to hold up the next one) and makes it ready to continu^^ 

°ff. If there were no tasks waiting; 
AVAILABLE would have changed the light to areen. In either 
case, AVAILABLE doesn't pass on control; if vou want this to 
happen, call PAUSE afterwards. ^ 

By cunning use of semaphores you can have demons: programs 
which lurk unseen until some event occurs, when they jump onto 
the stage and cast their spells. The clock monitor and the 
punt buffer manager in the example files are both implement'-d 
as demons: they don't appear unless there's work for them to 
do. This IS much better than constantly cycling round 
calling PAUSE when there's nothing interesting to do. 


2.4.2 Multi-state semaphores 


Sometimes it is useful to have values other than 
green for the variable, giving so-called counting 

as happily with counting semaphore 
replaced by SIGNAL. For most uses 


SEMAPHORE and 


WAIT work 
but AVAILABLE has to be 
AVAILABLE is the one to use, 


red and 
semaphores. 


2.4.3 Buffers . 


One of the supplied facilities using semaphores is 
buffer management routines. To define a buffer of 
you say 


a set of 
size 100 


100 BUFFER: foo 

lots of associated 
first-in, first-out 
first out devices, 
words 'deposit' and 


foo fetch EMIT 

will fetch and display a character from buffer foo if there is 
one available, while if the buffer is empty the task will be 


and this defines a data object with 
semaphores, counters etc. Buffers are 
devices, unlike stack which are last-in, 
Buffers may only be used via their monitor 
fetch , which work in the obvious way: 


I zn 
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put on a queue managed by a semaphore in the buffer. (As you 
may have guessed, fetch does a call to WAIT.) Similarly, 

ASCII Q foo deposit 

will put a Q in the buffer foo if there is room, and otherwise 
wait until the buffer is signalled as being nonfall. 

The files DELAY.BLK, BUFFER.BLK, SPOOL.BLK and WINDOWS.BLK 
have examples of the use of fetch and deposit and of WAIT ind 
AVAILABLE. 


2.5 The example files, 



2.5.1 DELAY.BLK 


Look first 
made from a 


at the file DELAY.BLK. This has a pseudo 
task that just increments a 


background 


doub.' 


locx 
e 


time 


precision variable every time it runs. The function 
returns the value of that variable. If your computer has a 
clock or timer that you can access, redefine 'time' to return 
the number of clock ticks as a 32 bit count. For ejcampie, 
TDELAY.BLK does this by calls to OSWORD which is an operatinq 
system call. 


Now red€ifine "seconds', "minutes' and 
stack quantity to the requisite number 
the BBC micro, the ticks are every 
definitions are 


"hours' to convert 
of clock ticks. For 
centisecond so the 


: seconds 100 U* ; 


and so on. 


This file also hus a clock monitor which is a demon that 
stays out of things when no tasks are waiting but stays active 
all the time, checking the clock, when any are viaiting. This 
means only one task is checking the clock, which is better 
than everybody having to keep looking at it. The .monitor uses 
some knowledge of the internals of semaphores to compensate 
for the fact that the delay queue isn't an ordinary first-ln 
first~out queue. We suggest you look at the other files 
before trying to v/ork out what it does; and we don't recommend 
you copy this procedure yourself since other sorts of queues 
are best managed in the standard ways. The clock monitor, 
like the print aemon defined later, is a background tasik. 
defined via BTASK: since it needs few (in this case, no) 
input/output facilities. Background tasks use less memory 
than foreground tasks. 
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2,5.2 bufff:r.blk 

This file implements a print buffer. You need to do a 
little installation as explained at the end of this section. 

The buffer works by setting aside an area (1000 bytes as 
delivered) for character storage when the printer isn't 
ready. There is a small task whose only job is to fetch from 
the buffer and output to the printer using EMITP. It is a 
background task since it doesn't use the dictionary or PAD 
areas at all. It writes to the printer using EMITP and no 
other task should use EMITP. Once it has been defined, we can 
re-vector the printer output in XEMIT+2 to deposit a character 
in the buffer and let the buffer task handle the actual 
output. Now whenever OUTPUTS has bit 1 set (e.g, '2 OUTPUTS 

!') output will go via the buffer. This will be true for all 
tasks that use EMIT or any standard xForth output, which 
always uses EMIT. 

This file also defines the semaphore 'printer' which - as 
long as everyone trying to print uses it - keeps output from 
different tasks separate. Tasks wanting to use the printer 
should do 


printer WAIT 

before trying to output and 

printer AVAILABLE 

when done. The control/P toggle for the slaving the printer 
to the main task output does not consult this semaphore: don't 
use it when the print monitor is loaded. The reason it 

doesn't work is that v;e thought it would be too risky to have 
your system hanging becfiuse you accidentally hit control/P and 
another task had failed to reset the semaphore. 

Before loading BUFFER.BLK you need to edit it to tell 
xForth how to read your printer status. This is often, but 

not always, possible by a BIOS call, and you may want to 
implement this yourself. Another common way is by a direct 
port read; an example is shown in the file for our North Stair 

Horizon. The idea is to return a TRUE flag if the printer is 

busy. (If you are completely stuck you can leave the 

definition as it is in the file, returning FALSE always so the 
buffer printer always tries to output and so will often hang 
uselessly.) The Torch has a special OSBYTE call that is 
implemented in T8UFFER.BLK. 

Depending on what you manage to do about the printer busy 
flag, on your printer speed, and on other characteristics of 
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your system, you may find it helpful to tune the printer- 
buffer performance by trying different combinations of the 
presence or absence of PAUSE in the words (EMITT) and (EMITP) 
defined in the file. Don't be afraid to experiment. 

It is possible, but less often useful, to define keyboard 
and you buffers. Samples are given in the file; you need to 
provide a status word (analogous to 2PRBUSY) for your vdu, and 
insert a '--^'continuation word at the end of the last print 
buffer definition block so that the other buffers get loaded 
too. 


2.5.3 SPOOL.BLK 

This file implements a background file listing spooler. A 
word PRINT-PILE reads a file name and assigns it to a 
temporary file in order to check it exists. If all is well it 
puts the name in a buffer which is monitored by a demon whose 
Dob is to wait for file names then print them out. This can 
work v/hether or not you have installed a print buffer. The 
point is that when you say 'PRINT-PILE abc.def' you get 
control immediately and you can send another file to the 
printer in the same way, and so on until the file name bufft^r 
fills up. The supplied version allows at least 5 files at a 
time; more if they have short names. 


2.5.4 WINDOWS.BLK and TASKDEMO.BLK 

Full windowing requires a memory mapped display. Some VDUs 
such as the BBC micro allow hardware defined windows for both 
text and graphics, and the file WINDOWS. BLK shows how to take 
advantage of these. If you have more powerful facilities, you 

should find it easy to modify the code.^ If all you have is a 
standard VDU you can still manage if you write software to 
take care that ail output stays within its window. 

The method is to define a new set of USER variables that 
specify text and graphics window edges, and graphics cursor 
position. (The text cursor position is kept in >LINE and OUT 
which is consistent with normal xForth usage). Then we define 
words make , 'open' and 'close' which create such windows and 


1. For example, if you can read the contents of a window you 
can handle overlapping windows by arranging that when a window 
iS opened you store the existing contents somewhere, and 
restore them when the window is closed. Each task will need 
its own temporary storage area, big enough to hold a complete 
copy of the window. This can even be done with the BBC micro 
and Torch. 
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control access to the screen. For example 

" Headlines" twindow make 

makes a text window with a label "Headlines" at the top left. 
And 

" Brownian motion" gwindow make 

makes a graphics window with a suitable label. In each case 
the window edges are given by the values of the variables at 
the time make is called; for example, the left edge of a 
task's graphics window is given by xl. 

To use a window, you have to say 

twindow open 

before sending output, which checks a semaphore to see if the 
screen is available, then sets up the windows. After writing 
to it for a while, say 

twindow close 

to restore the default text area and flag the screen as 
available to some other task. It would be reasonable to do 
this after every line or two of text. With graphics, how 
often you close the window to give others a chance depends on 
the application. 

Torch users can load the file TASKDDEMO. BLK to get a 
running demonstration with 2 graphics windows, 2 text windows 
and a reserved window at the bottom of the screen where normal 
editing, compilation and so on can take place. Try typing DIR 
or VLIST and see what happens. When you pause the output 
using control/S the other tasks will go on while the display 
is help up. As well as the tasks owning the windows, there 
are several other tasks like the clock monitor running, and 
you should still find it feasible to load the print buffer and 
print spooler and use them. To get a four colour display we 
use mode 1 which makes editing a bit painful because the 
screen width is too small, but if you use mode 0 instead you 
will find you can edit quite happily while the demonstration 
is going on. It may help if you modify the 'log' task to be 
less greedy in its use of the window. At present it may print 
out several lines before giving anyone else a chance to run. 



I zo 
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2.6 S ummary; task types and sta tes. 


2.6.1 Task types 

A task may be one of two types: a normal task or a 
background task. A normal task can call all xPorth words^ 
though unless it is the normal user task it usually only has a 
tiny private dictionary so it should not attempt to compile 
anything. A background task takes up less room than a normal 
task but has no terminal input buffer, has smaller stacks, and 
has no PAD and only a few user variables. Nevertheless, as 
long as it does no file name operations, or calls to WORD or 
number formatting words or most string words, it can do a 
great deal. For information about how to change stack sizes 

etc of tasks, see 'taskframe' and 'btaskframe' in the 
glossary. 


2.6.2 Task states 

A task may be in any of 3 states: stopped, active and 
waiting. 

Tasks are stopped when first created or when they have 
attempted to run after STOP has been applied to them (seej 
..ater). in particular, a task goes into the stopped state if 
it calls QUIT or if it runs to completion. 

Active tasks may be running or ready to run. The running 
tasK is the one that has control at any particular moment and 
the address of its user variable area is returned by the word 
UP@. Tasks that are ready to run get their chance when PAUSE 
IS called, either explicitly or implicitly as in KEY. They 
also gfit their chance to run if a running task gets moved to a 
queue by WAIT or by one of the DELAY words, 

VVaiting tasks may be waiting in a semaphore queue, where 
they were put by WAIT and whence they may be removed by SIGNAL 
or by AVAILABLE, or in the clock queue where they were put by 
a DELAY word and whence they may be removed bv the 
clockmonitor. ‘ ' 
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2.7 General task m a naq etnent 


To start a task that is in the stopped state, use ST/^vIiT. 

To stop one that is active or waiting use STOP. Thus 

taskl START task2 STOP 

can be called from the main user task. A STOP does not take 
effect until the next time a task tries to run; it is 
equivalent to inserting QUIT in place of the instruction the 
task is next due to execute. As v;e saw' before, a task will 
always STOP itself if it calls QUIT or if it reaches the end 
of its definition. 

To output the name of a task, use .TASK as in 

taskl .TASK 

which would merely output 'taskl'. If you have loaded the 

file DELAY.BLK you can output the names of all active tasks by 
using .TASKS which takes no arguments, and you can output the 
names of ail tasks that are waiting for the clock by usina 

.DELAYED which cilso takes no arguments. 

V\;hen tasks have been dtrCined, you have to be rather careful 
about uses of FORGET or EMPTY. You must make sure all tasks 
that will be remov^ed from the dictionary are stopped, by 
Ccilling STOP for them then signalling any semaphores the^y are 
waiting on. (For example, it is ok to type "delayed 

AVAIYABYE' as often as required to flush out the delayed 
queue.) Alternative.ly you can .reinitialize all seaiaphores by 
repeating 

0 0 1 ::*raa 2 i 

for every semaphore, replacing 'sema' by the appropriate:; 
name. In that case any tasks that were v^aiting on them are 
lost unless restarted with START. 

If you call COLD, there is an immediate call to EMPTY and 
then all tasks are killed on the spot. The main user task 
will restart after the code in XSIGNON has been executed. If 
you want to make xForth come up running severiil tasks either 
on initial startup or after COLD is typed, you can vector 
XSIGNON to a word that starts all necessary tcisks. Don't 
forgcit to run PROTECT before you save the m.odified system. 



BliMriitrr' 
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Chapter 3 
Trouble 


Obviously we want to know about any bugs you discover, but 
our experience, believe it or not, is that most problems are 
caused by the fact that xForth reaches the parts of your 
operating system that most programs don't. 

If you have trouble getting xForth to run at all, there is 
possibly a bug in the BIOS of your CP/M. We have been amazed 
at how many well-known and respected systems have bugs in 
their versions of CP/M, The commonest are as follows: 

Failure to produce output on vdu, or crash after disc 
access e.g. Zorba. 

The most likely problem is that the BIOS uses some 
Z80 iidditional registers and fails to restore them. 
Use the 8080/CPM1.4 version of xForth. 

VDU output cind terminal input OK but can't handle disc 
files, e.g. listing a file you know to exist gives long 
strings of (i.e. nulls), e.g. early ALTOS. 

* The random access disc routines are not properly 
implemented. Use the B080/CPM1.4 version of xForth. 

“ Cursor fails to appear, but input and output are ok 
except that you don't know where you are on screen, e.g. 
Sharp with Xt^^l CPM, early Gemini. 

* The cursor is flashed in software and is not 

interrupt driven. The only effective solution is to 
insist that your supplier give you a bug-free 
version of CPM. In the meantime, put up with the 
lack of cursor or else write your own word to read 
keys (using CPM-CALL for function 6, for example) 
and put it in XKEY. You will lose most multitasking 
abilities. It might be worth trying to build a 

flashing cursor with the xForth delay words: some 
character appears for so many clock ticks, then is 
removed, then is replaced and so on. 
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xForth greatly slows down a system running MP/M 
multitasking DOS. 

* What can you expect when two multitasking 
compete for resources! You can re-vector 
above, and give up most multitasking, or 
persuade other users to use xForth instead! 
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Appendix A 

Alphabetic list of words in xForth 


A .l Words deleted. 


.COVOC .CUVOC ;S (DO) (LOOP) (+LOOP) (OP) BLISTS FILE-INIT 
INDEX LISTS LIT PRINTER-ON? SEC/BLK TRIAD XCAMCEL 

Also, OBRANCH has been renamed 7BRANCH and CPM-CALL and 
CPM-CALLb have been renamed DOS-CALL and DOS-CALLb 



A.2 Words unchange d. 


i 

!CSP 

II 

# 

#->$ 

#> 

#BUFF 

#files 

#s 

$! 

$ + 

$-># 

$< 

$ = 

$FIND 


's-FCB 

's-STATUS-BYTE 

'th-FILE 

( 

(ASCII) 

(EDITOR) 

{ file-voc) 

(FIND) 

(FLUSH) 

(ID) 

(LINE) 

(skip-until) 

(skip-while) 

( [ , ] VARIABLE) 

([ ] VARIABLE) 

* 

*/ 

*/MOD 

Hh 

+ ! 

+- 

+ LOOP 


— 

—> 

-1 

-TRAILING 



.CPU 

.LIME 

.R 

• SIZE 

.STACK 

•VERSION 

/ 

/MOD 

0 

0< 

0 = 

0> 


1 + 

1+! 

1- 

1-! 

2 

2! 

2* 

2 + 

n 

4L 

20 

2CONSTANT 

2 DROP 

2DUP 

2 OVER 

2K0T 

2SWAP 

2VARIABLE 

3 

79-STANDARD 

: 

t 

;CODE 

< 

<# 

< = 

<> 

<CMOVE> 


> 

> = 

>IN 

>LINE 

>R 

? 

?COMP 

?CSP 

?DEPTH 

?DUP 


I 
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7ERR0R 

7EXEC 

7PAUSE 

7TERMINAL 

AGAIN 

ALLOT 

B/BUF 

BASE 

BINARY 

BL 

BLOCK 

BRANCH 

Ci 

C# 

C@ 

CAN-KEY 

close-files 

CMOVE 

CONFIG 

CONSTANT 

COPIES 

COPY 

CREATE 

CRS 

CURRENT 

D+ 

D. 

D.R 

D< 

D= 

DEFAULT 

DEFINITIONS 

DLITERAL 

DMAX 

DO 

DOES> 

DP 

DPL 

DUP 

ELSE 

EMPTY 

EMPTY-BUFFERS 

ENDOF 

ENSURE-LINE 

ERROR 

EXECUTE 

fassign 

FCREATE 

FILL ■ 

FIND 

FORGET 

FORTH 

HLD 

HOLD 

IF 

IMMEDIATE 

INTRPT-CHAR 

J 

LEAVE 

LFA 

LOAD 

LOOP 

M/MOD 

MAX 

MOD 

MOVE 

NEXT 

NFA 

NUMBER 

OPEN 

OVER 

P! 

PAGE 

PFA 

QUERY 

R# 

R> 

R@ 

RESTORE-$$$ 

REVERSE 

RP! 

RP@ 

SAVE-BUFFERS 

SCR 

seg-size 

SIGN 

SP@ 

SPACE 

STRING 

SWAP 

SYSGEN 

THEN 

TRUE 

TYPE 

U. 

U.R 

UCHAR 

UNTIL 

VARIABLE 

VLIST 

WARM 

WARNING 

WORD 

wrap 

XOFF-CHAR 

XOK 


7LOADING 

7PAIRS 

@ 

ABS 

AND 

ASCII 

BEGIN 

BELL 

BLANKS 

BLK 

BUFFER 

BYE 

C, 

C/L 

CASE 

CLOSE 

COLD 

COMPILE 

CONTEXT 

CONVERT 

COUNT 

CR 

CSP 

CTRL 

D4— 

D- 

D0< 

D0= 

DABS 

DECIMAL 

DEL-KEY 

DEPTH 

DMIN 

DNEGATE 

DOS-CALL 

DOS-CALLb 

DROP 

DU< 

EMITP 

EMITT 

ENDCASE 

ENDIF 

EOF 

ERASE 

EXIT 

FALSE 

FENCE 

FILE 

FIRST 

fname! 

HERE 

HEX 

I 

ID. 

in-range7 

INSTALL-$$$ 

L/S 

LATEST 

LIST 

LITERAL 

M* 

M/ 

MESSAGE 

MIN 

MYSELF 

NEGATE 

NOOP 

NOT 

OR 

OUT 

P@ 

PAD 

PICK 

PREV 

R/W 

RO 

REPEAT 

REPLACED-BY 

ROLL 

ROT 

S->D 

SO 

SEE 

SEE-FILE 

SMUDGE 

SP! 

SPACES 

STATE 

SYSADAPT 

SYSFILE 

TIB 

TOGGLE 

u$ 

U* 

U/MOD 

U< 

UPDATE 

USE 

VOC-LINK 

VOCABULARY 

WHILE 

WIDTH 

XCUR30R 

XNUMBER 

XOR 

XPAGE 
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XPROMPT XRUBOUT 

[,]VARIABLE [COMPILE] 


XSIGNON [ 
[]VARIABLE ] 
} 
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A.3 Vocabulary 


listing with de finitions 



of new words. 


These are all the words in the vocabulary FORTH in xForth 
2. Where they are changed from xForth 1 or new to xForth 2 
they are defined here. The usual notation of the xForth 
technical manual is used: stack pictures are of the form 

( stack before - stack after ) 

unless text is read from the input in which case they take the 
form 


( stack before +++ stack after ). 


Stack items are 
$ 
c 

flag 

n 

u 

d 

du 

addr 


string (address and count), 
character or byte, 
logical, 

16 bit integer, 

16 bit unsigned integer, 

32 bit signed integer, 

32 bit unsigned integer, and 
16 bit address. 



1 

♦ 

Unchanged 

ICSP 

Unchanged 

ft 

Unchanged 


Unchanged 

#->$ 

Unchanged 

#> 

Unchanged 

#BUPF 

Unchanged 

#files 

Unchanged 

#S 

Unchanged 

#TIB 

(-add 


A USER variable containing the length of text in the 
terminal input buffer when it is being used for input. 


DUVARS (-n ) 

IP 

W 
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A CONSTANT returning the number of USER variables so far 
defined. 


$! 

$+ 

ar'£ 


Unchanged 

Unchanged 

Unchanged 


$->U# 


( $ - du flag ) 


Convert string $ to an unsigned double number and leave the 
result under a flag which is TRUE if and only if the string 
consisted entirely of digits in the present base. 


$< Unchanged 

$= Unchanged 

$break ( $ c — $1 $2 flag ) "String break" 

If character c is contained in string $, return $1 and $2 
such that $ is $2c$l and leave a true flag. If c is not 
contained in $ then $2 is empty, $1 is identical with $, and 
the flag is false. 



$DIR ( $-) 

Send a directory listing to the current output device 
corresponding to the ambiguous file and user specification 
contained in string $. See the entry for DIR. 


$FIND 

I 

's-FCB 


Unchanged 

Unchanged 

Unchanged 


's-name 


file-$ ) 


Return the name of the operating system file currently 
assigned to 'file', in the form A:NAME.EXT[u] where u is a 
number in the range 0 to 15. 



's-STATUS-BYTE 

'th~FILE 

( 

(ASCII) 


Unchanged 

Unchanged 

Unchanged 

Unchanged 
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(EDITOR) 

(file-voc) 

(FIND) 

(FLUSH) 


Unchanged 

Unchanged 

Unchanged 

Unchanged 


(get) 


Internal use; do not use. 


(ID) Unchanged 

(KEY) ( c ) 


The default code for input stream 0. (See INPUTS.) Returns 
a character typed at the console, calling PAUSE as often as 
necessary if a character is not ready. 



(LINE) Unchangetd 

(prompt) ( - ) 

The default prompt message: a 53 tack display. 


(SIGNON) ( —- ) 

The default signon command which displays the text printed 
aftei cold start. If the contents of XSIGNOM are changed from 
(SIGNON) to a user defined word then xForth will execute that 
word on startup. 



(skip-until) 

Unchanged 

(skip-while) 

Unchanged 

([,1VARIABLE) 

Unchanged 

([]VARIABLE) 

Unchanged 

* 

Unchanged 

*/ 

Unchanged 

*/MOD 

Unchanged 

4 - 

Unchanged 


Unchanged 


Unchanged 

+LIST 

( u - ) 


Call LIST for all blocks from block u until 
starting with EOF is read. 


+LOOP Unchanged 


a block 
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t Unchanged 

Unchanged 

( +++ ) 

Ignore all text until the end of the current input line 
being interpreted. Lines are terminated with carriage return 
(control/M) during input from all streams except when BLK is 
nonzero, when they are all 64 characters long. 



—> Unchanged 

-1 Unchanged 

-TEXT ( addrl nl addr2 — n2 ) 

Compare two strings over the length nl beginning at addrl 
and addr2. Return zero if the strings are equal. If unequal, 
return n2, the difference between the last two characters 
compared. 


-TRAILING Unchanged 

. Unchanged 

." Unchanged 

.BASE (-) 

Type the current base, in decimal, on the currently 
selected output stream(s), followed by a space. 


.CPU 

• LINE 

• R 

.SIZE 
. STACK 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


.STORE (-) 


Type on the standard output an unsigned number which is the 
number of bytes between the the current dictionary top (HERE) 
and the value stored in DICTLIM. 



.TASK ( addr - ) 

For the task whose user variable base is at addr, print its 
dictionary name on the currently selected output stream(s). 
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.VERSION 

Unchanged 

/ 

Unchanged 

/MOD 

Unchanged 

0 

Unchanged 

0 ! 

( addr-) 

Store 

0 in the two bytes start 

0 < 

Unchanged 

0 = 

Unchanged 

0 > 

Unchanged 

1 

Unchanged 

1 + 

Unchanged 

1 +! 

Unchanged 

1 - 

Unchanged 

1 -! 

Unchanged 

Isttime 

(-ud ) 

Leave 

on the stack a double i 

time the 

soonest delayed task 

Undefined 

if there are no delayed 

2 

Unchanged 

2 ! 

Unchanged 

2* 

Unchanged 

2 + 

Unchanged 

2 - 

Unchanged 

2 / 

( nl - n2 ) 


.ng at addr. 


is due to 


which is the 
be restarted. 


Replace ni with its arithmetic right 
shifted right but the highest bit 
Equivalent to floored division by 2, i.e. 
is -2. 


shift, i.e. nl is 
remains the same. 
3 2/ is 1 but -3 2/ 


2 @ 

2C0NSTANT 

2DR0P 

2DUP 

20VER 

2 ROT 

2SWAP 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 
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2VAR.IABLE 

Unchanged 



3 

Unchanged 



4 

Leave 4 on 

the 

stack. 

79-STANDARD 

Unchanged 




Unchanged 



f 

Unchanged 



; CODE 

Unchanged ( 

but 

see comments on direct threaded code 

< 

Unchanged 




Unchanged 



<= 

Unchanged 



<> 

Unchanged 



<CMOVE> 

Unchanged 



<MARK 

(-addr 

) 

"backward mark" 



A system word extension. Used at the destination of a 
backward branch. addr is typically only used by <RESOLVEi; to 
compile a branch address. 



<RESOLVE 


addr - ) "backward resolve" 


A system word extension. Used at the source of a backward 
branch after either BRANCH or 7BRANCH. Compiles a branch 
address using addr as the destination address. 


= Unchanged 
> Unchanged 
>= Unchanged 


>BODY 

( cfa-pfa ) 


Replace 
stack with 
address) . 

the execution address (code field address) on the 
the corresponding body address (parameter field 

>IN 

>LINE 

Unchanged 

Unchanged 


>MARK 

( - addr ) "forward mark" 


A system word extension. Used at the source 
branch. Typically used after either BRANCH 

of a forv/ard 
or ?BRANCH. 


Compiles space in the dictionary for a branch address which 
^ will later be resolved by >RESOLVE. 


31 






xForth 2 (c) Alistair Mees 


>R Unchanged 

>RESOLVE ( addr - ) "forward resolve" 

Used at the destination of a forward branch. Calculates 
the branch address (to the current location in the dictionary) 
using addr and places this branch address in the space left by 
>MARK. 


? 

?BRANCH 
7C0MP 
?CSP 
?DEPTH 


Unchanged 

Same as OBRANCH in xForth 1. 

Unchanged 

Unchanged 

Unchanged 


7DICT 


( — ) 


Check that the PAD (which lies above HERE) is at least 96 
bytes below the . value stored in DICTLIM and call ERROR if 
not. 


?DUP 
7ERR0R 
?EXEC 
?LOADING 
7PAIRS 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


7PAUSE Unchanged. 


But note that if output is suspended using XOFF-CHAR other 
tasks may still execute. 


7STACK (-) 

Check that the stack pointer lies between Si @ and SO 
and that the return stack pointer lies between Rl @ and RO 
and call ERROR if not. 


7TERMINAL 

@ 

ABORT 


Unchanged 

Unchanged 

( —~ ) 
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Clear the stack and call QUIT. No message is printed. 


ABS Unchanged 

active ( --addr ) 

A variable which points to the tail of the circular list of 
currently active tasks. 


advance ( addr - ) 

Adjust the circular list tail pointer stored in addr so 
that the current head becomes the tail and the successor of 
the current head becomes the new head. 


AGAIN 

ALLOT 

AND 


Unchanged 

Unchanged 

Unchanged 


append ( addrl addr2 - ) 

Add the item at addrl to the circular linked list whose 
tail pointer is addr2. Used typically to append the task 
which has user area base at addrl to the tail of the circuliir 
list whose tail pointer is at addr2. 


ASCII Unchanged 

AVAILABLE ( addr - ) 

In conjunction with WAIT, manage a two-state semaphore. 
That is, assuming addr is the address of a semaphore, check 

whether there are any tasks queued by the semaphore. If so, 

remove the first in the queue and add it to the tail of the 

active list, but do not call PAUSE. If there are no tasks 

queued, set the semiiphore's counter to 1. See WAIT and 
SEMAPHORE and SIGNAL. 


B/BUF 

BASE 

BEGIN 

BELL 

BINARY 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 
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Unchanged 
BLANKS Unchanged 

BUK Unchanged 

blkdestroy ( u - ) 

If virtual memory block u is in a buffer, mark the buffer 
as empty without writing its contents to disc. 


BLOCK Unchanged 

BRANCH Unchanged 

BTASK: { +++ ) 

Define a background task; that is, allocate space for 12 
USER variables (the only public ones being SO Si RO Rl XERROR 
INPUTS OUTPUTS restart-time) and initialize them according to 
the pattern in btaskframe, but with the values offset 
correctly. Then perform various pre-initialization tasks, and 
finally switch to compilation mode. If ' j' is executed 
successfully the-result is to define a background task that is 
initially in the stopped state. A background task has only 
the user variables indicated and in particular has no 
dictionary or PAD so it may not call WORD . .R #->$ $-4- 
LOAD-FILE DIR or any other number formatting word or string 
handling word (or any other word) that uses the PAD. 


btaskframe ( - addr ) 

The address of a 4 byte region which is used to determine 
the size of the stacks in a background task. The values are 
the size of the stack and the size of the return stack in that 
order. On delivery the stacks are both 40 (decimal) bytes 
long. 


BUFFER Unchanged 

BUFFER: ( n +++ ) 

Define a buffer of size n, where n lies between 1 and 
10,000. This buffer is only to be accessd via the monitors 
'deposit' and 'fetch'. Example: 

1000 BUFFER: printbuffer 

When 'printbuffer' is executed it leaves its address on the 
stack. See also 'buffinit' which is called on buffer creation 
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but may be called, with care, at other times. 

buffinit ( addr - ) 

Initialize the buffer at 'addr' so that it is empty, has no 
waiting tasks, and is ready for use. 


BYE 

Unchanged 

C! 

Unchanged 

C£ 

Unchanged 

c. 

Unchanged 

C/L 

Unchanged 

C9 

Unchanged 

CAN-KEY 

Unchanged 

CASE 

Unchanged 

CFA 

( pfa- 


Return the execution address (code field address) 
corresponding to the body address (parameter field address) on 
the stack. Not necessarily equivalent to 2~ as it was in 
xForth 1. 



CFA->NFA ( cfa - nfa ) 

Return the code field address corresponding to the name 
field address. 


ch-in-str? { c $ - n ) 

If character c is to be found in string $, return its 
position in the string (with the first character treated as 
i). If not, return 0, 


Unchanged 

Unchanged 

Unchanged 

Unchanged in meaning; does additional jobs. 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


CLOSE 

close-files 

CMOVE 

COLD 

COMPILE 

CONFIG 

CONSTANT 

CONTEXT 

CONVERT 


I n 
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COPIES 

COPY 

COUNT 


Unchanged 

Unchanged 

Unchanged 


CR 


Unchanged 


But note that it calls ?PAUSE as it has done since xForth 

1.21 


CREATE 

CRS 


Unchanged 

Unchanged 


CS-SIZE 

( — n ) 

Return 

the number of bytes in the cold start 

used to initialize the USER variables from SO up 

CS-TABLE 

{ - addr ) 

Return 

the address of the cold start table. 

CSP 

Unchanged 

CTRL 

Unchanged 

CURRENT 

Unchanged 

CURSOR 

( row col-) 

Move the cursor to the given row and column. 

the value 

of col and >LINE to the value of row. 

D+ 

Unchanged 

- 

Unchanged 

D- 

Unchanged 

D. 

Unchanged 

D.R 

Unchcinged 

D0< 

Unchanged 

DO- 

Unchanged 

D< 

Unchanged 

D= 

Unchanged 

DABS 

Unchanged 

DECIMAL 

Unchanged 

DEFAULT 

Unchanged 

defdrv 

{ —- n ) 
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Return the presently selected drive known to CP/M as the 
default drive. 


DEFINITIONS Unchanged 
defuser ( - n ) 

Return the CP/M user number that was in force the last time 
COLD was called. This will be used by file operations 
(including DIR) if no user number is specified. Typically 0. 


DEL-KEY Unchanged 

delayed ( - addr ) 

A semaphore used by the clock monitor to hold a queue of 
t^isks waiting to be restarted when the value returned by 
'time', becomes greater than or equal to their restart-times. 
Not for use. except by the clock monitor. 


DELAYUNTIL ( ud - ) 

Set the USER variable 'restart-time' to ud. Then remove 
the present task from the active list and insert it into the 
list managed by the semaphore 'delayed', such that the list is 
in increasing order of restart times. 


deposit ( c addr - ) 

A monitor for buffers. If the buffer at addr is not full, 
deposit byte c in the buffer, and signal that the buffer is 
not empty. If the buffer is full, remove the present task 
from the active list and add it to the queue managed by the 
buffer and its monitors. 


DEPTH Unchanged 

DICTLIM ( - addr ) U 

A USER variable containing the address used by ?DICT to 
determine whether the dictionary is within bounds. Set on 
delivery to be 2 less than the contents of Si. 
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DIR 


( +++ ) 


Read the next WORD, delimited by blanks, from the currently 
selected input stream. Convert all letters to upper case and 
then attempt to interpret it as an ambiguous file and user 
specification (afus) as follows: 

afus: drive:name.ext[u] 

where 'drive;' is any drive specification legal for the 
system, 'name' is up to 8 characters legal for CP/M file 
names, together with ? ^and * with their usual meanings; 'ext' 
3 such characters; and 'u' is a user number in the range 0 to 
15. All parts are optional and have defaults defdrv for the 
drive; defuser for the user number; and empty for the name and 
extension except that if both are empty they are treated as 

-k ^ ' 


DLITERAL Unehanged 
DMAX Unchiinged 
DMIN Unchanged 


□NEGATE 

Unchanged 

DO 

Unchanged 

DOES> 

Unchanged 

DOS-CALL 

Unchanged (but was 

DOS-~CALLb 

Unchanged (but was 

DP 

Unchanged 

DPL 

Unchanged 

DROP 

Unchanged 

DU< 

Unchanged 

DUP 

Unchanged 

echo 

{-addr ) 


called CPM-CALL in some versions), 
called CPM-CALLb in some versions). 


A variable which is used by LOAD-FILE to determine whether 
each line of input from streams other than the terminal or 
.BLK files is to be copied to the currently selected outputs 
before it is interpreted. 







ELSE Unchanged 

EMIT ( c ) 

Send the character c to each of the currently selected 
output streams. See OUTPUTS and XEMIT. 
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EMITP 
EM ITT 
EMPTY 

EMPTY-BUFFERS 

ENDCASE 

ENDIF 

ENDOF 

ENSURE-LINE 

EOF 

eof ? 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

( —- flag ) 


A constant used by EXPECT to signal to LOAD-FILE that the 
end of file has been reached on an input stream. See EXPECT 
and XEOF. 


<501? (-flag ) 

Return TRUE if a return ^M or an end of file has just 
been read,.or if at the end of a block when BLK is nonzero. 


ERASE 


Unchanged 


ERR>IN 


addr ) 


A variable which is set by STD-ERROR to the value of >IN 
when the error occurred. Used by WHERE. 


ERRBLK ( - addr ) 

A variable which is set by STD-ERROR to the value of BLK 
when the error occurred. Used by WHERE. 


ERROR 

EXECUTE 

exist-delayed 


Unchanged 
Uncha nged 

(-addr ) 


A semaphore us(5d to put the clock monitor into a waiting 
state if there are no delayed tasks to execute. Not to be 
used except by the clock monitor. 
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tJnchanged. (The code compiled by 
EXPECT ( addr n - ) 

Reads up to n characters from the currently selected input 
stream and stores them in a string beginning at addr. Allow 
editing by character and line deletion when the characters in 
DEL-KEY and CAN-KEY are received. The string is terminated 

when n^ characters have been read, or if return “M or end of 
file Z is read. A space is output if return is read. The 

USER variable SPAN is set to the number of characters actually 
put in ^the buffer. Tabs are expanded to multiples of 
tabsize', line-feeds are ignored, and "Z, as well as being 

treated as a carriage return, causes the code in XEOF to be 

executed after the line has been interpreted. These changes 
are to allow input from text files. See LOAD-FILE. 


EXPECT$ { addr n - addr n' ) 

As EXPECT but return the string read. 


fallocate ( file - n ) 

If the file is alre;ady allocated to a virtual memory 
segment, return the number of the segment (0 to #FILES-1). If 
the file is not allocated, allocate it an unused segment if 
there is one and return its number. Otherwise return 0. (Note 
that SYSFILE is permanently allocated to segment 0.) 


FALSE 
fassign 
PCREA'l’t; 
FENCE 


Unchanged 

Unchanged (but it is better to use fallocate). 

Unchanged 

Unchanged 


PENCE-BELOW ( +++ ) 


Read the 
b Panics, and 
Example: 


next word from the input stream, delimited by 
call ERROR if it is not in the dictionary. 


FENCE-BELOW word 


Then set the value of FENCE to what HERE was before 'word' was 
created. 
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fetch 


( addr-c ) 


nonempty, remove a character c 
from It and signal that it is nonfull. If it is empty, remove 
tne current task from the active list and put it on a queue 
managed by the buffer and its monitors deposit and fetch. 


FILE 

FILL 

FIND 

FIRST 

fnamei 

FORGET 

FORTH 

frelease 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


Close the fiie that is allocated to virtual memory segmeni 
n, and mark the seg;uent as unused. 


GET-FILIi: 


( .j - addr ) 


Given a virtual memory block number u, return the address 
of the corresponding file and the operating system sector ui 
of the start of tnat block. If the block corresoonds to no 
iile, call ERROR. 


getuser ( - n ) 

Return the presently selected 


M user number, 


HERE 

Unchanged 

Hi-X 

Unchanqed 

MLD 

Unchanqed 

ilOLD 

i,J n changed 

I 

Unchanged 

ID. 

Unchanged 

IF 

Unchanged 

IMMEDIATE 

Unchiinged 

in-addr 

( —- add: 


Return the 
interpreting. 


ddress of the next character to be read v/hen 


I 7r\ 
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in-range? Unchanged 

INPUTS ( - addr ) 


A UShR variable whose least signi 
what input stream is selected when BLK 
input trom the stream with the lowest 
setting the lowest bit by '1 INPUTS ' ' 
taken trom the CP/M terminal device.' 
is returned by KEY. See KEY and XKEY. 


ficant 4 bits determine 
is zero. KEY will take 
^bit set; conventionally, 
will cause input to be 
If INPUTS is 0 then EOF 


INSTALL-$$$ 

INT.UKPRET 

INTUPT-CHAR 

J 


Unchanged 

Unchanged 

Unchanged 

Unchanged 


(but vectored through XINTERPRET). 


KEY 


{ — c 




11 the 4 low order bits 
EOF. Otherwise, execute the 
XKEY corresponding to the 
^•9* if key is set to 
XKt:Y + 2*3-XKEY+6. See INPUTS 


of INPUTS are set to 0, return 
code pointed to by the element of 
lowest order set bit of INPUTS, 
8=2''3 then execute the code at 
and XKEY. 


L/S 


Unchanged 


LAST-KEY ( - c 

Return the last byte 


) 

input from the CP/M terminal device. 


LATEST 

Unchanged 

LEAVE 

Unchanged 

LFA 

Unchanged 

LIMIT 

(-addr 


Execute the code pointed to by XLIMIT. Used by 
determine how much space is available for xForth- 
should be 1 more than the last address permitted. 


COLD to 
'addr' 


LIST 


Unchanged 


LIST-FILE 


( f4*-h ) 
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atte»p? et'\t "Ts" blanks, and 

spocification. If unsnccessf,,? “"ffb^^uous file and user 
the file does not exLt cfll ERrS or?”’'-- Otherwise, if 
in a .BLK file then 1 st it in t'h if the tile 

Otherwise, list it as an ierT, ^°™at used by LIST. 

pl=B^whe~‘c"l„tr":f;L S 

Un^feed ^oes to all currently selected outp« streams • 

be Llled -m'^cLsc CR ti 


literal 

LOAD 

load-file 


Unchanged 

Unchanged 

( +++ ) 


attempt \o“°'inte"rpret'’\t" a't'^ delimited by blanks, and 

specification ^ ^ f" unambiguous file and user 

tiriiirars- 

0the?wisr3e^L1 i-u? 

°£ input; if the viriable -echo- is set ?o 

ePc9-ou-f^^s^^;re \\"temrtrn^%i“^te%rft^ ” 

Note that even althouah BLK is set to n t-hJ i ^ • 

about termint,n„rT normal rules 

(deliraitL bv oareL co,aments and execution conditionals 
i^xirairt-a oy parens () and braces {}) are relaxed The im-o- 

tUe IS terminated by EOF i e ''7 PiiMe fr.. f 
npqfAH QT ^ • 6, tilBs tov loadinQ may be 

t-sted and .BLK and others may be mixed arbitrarily. ^ 


LOCAL 


addrl addr2 - addrS ) 


Given 
und the 
another 
for that 


the USER variable address addrl for the current task 
user variable base addr2 (typically belonging to 


task) return the 
base. Ex^iinple: 


corresponding USER variable address 


SO depthtask LOCAL 


LOOP 

M* 

M/ 

M/MOD 

MAX 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


maxdrv 


n ) 
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Return the number of drives xForth thinks the system has. 


MESSAGE 

MIN 

MOD 

MOVE 

MYSELF 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


n-TAB 


( u-) 


Used lor zoned printing. Output one or more spaces to make 
OUT a muitiple of u, if this is possible without OUT exceeding 
C/L, and provided there would still be at least u positions 
leit on the line. Otherwise execute CR. 


NEGATE 

Unchanged 

NEXT 

Unchanged 

NFA 

Unchanged 

NOOP 

Unchanged 

NOT 

Unchanged 

n o t ~in- memo r y ? 

Internal 

NUMBER 

Unchanged 

OF 

Unchanged 

off 

( addr — 


Set the two bytes at addr to FALSE. 


on ( addr-) 

Set the two bytes at addr to TRUE. 


OPEN Unchanged 

OR Unchanged 

OUT Unchanged 

OUTPUTS ( — addr ) U 

A USER variable determining which output streams are 
selected. EMIT sends its byte to each stream whose bit is 
set; there are 4 streams, corresponding to the 4 low order 
bits of OUTPUTS. Conventionally, output stream 0 is the VDU 
(i.e. the CP/M standard output device). OUTPUTS is set to 1 


i zo 
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on cold start and after errors, so that output goes to the VDU 
in such cases. 


OVER 

Unchanged 

P! 

Unchanged 

P@ 

Unchanged 

PAD 

Unchanged 

PAGE 

Unchanged 

PAUSE 

( — ) 


Move the present task to the tail of the active list and 
transfer control to the task which is now at the head of the 
active list. Should always be used in "busy waits" (loops 
which do nothing while waiting for some event to happen such 
as a key press) though semaphores are the preferred and 
usually more efficient way to handle cases such as this. Is 
implicitly called by KEY if there is no character waiting to 
be read, and by 7PAUSE if the output pause character in 
XOFF-CHAR has been pressed. 


PFA Unchanged 

physical-eof? ( - flag ) 

TRUE if the last disc input operation attempted to read an 
unallocated operating system sector. 


PICK Unchanged 
PREV Unchanged 
PROTECT 

Unchanged except that it calls EMPTY after setting other 
variables. This ensures the vocabulary links are correct. 


QUERY Unchanged 
QUIT (-) 

If the current task is the main user task, clear the return 
stack, set interpret mode and select console input. 
Otherwise, put the task in the stopped state. 
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R# 

Unchanged 


R/W 

Unchanged 


RO 

Unchanged 


Rl 

(-addr ) 

U 


A USER variable containing the return stack, lower bound; 
used by 7STACK in checking that the stack is within bounds. 



R> 

R@ 


Unchanged 

Unchanged 


remove 


addrl - addr2 ) 


Assuming addrl is the address of a 
circular list tail pointer, remove the 
leave its address addr2. Typically used 
a queue. 


variable which is a 
head of the list and 
to remove a task from 


REPEAT Unchanqed 

REPLAGED-BY Unchanged 

restart-time ( - addr ) U 

A USER 2VARIABLE containing the time a task will be 
restarted by the clock monitor. Only valid when the task is 
on the list managed by the semaphore 'delayed'. 



RESTORE-$$$ 

REVERSE 

ROLL 

ROT 

RP ! 

RP@ 

S~>D 

50 

51 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

(-addr 


U 


A USER variable containing the stack 
7STACK to check that the stack is within 


lower limit, 
bounds. 


Used by 


SAVE-BUFFERS 


Unchanged 
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SCR 

SEE 

SEE-FILE 

seg-size 

SEMAPHORE 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

( +++ ) 


A defining word used to define semaphores as in 


SEMAPHORE printer 


which defines a semaphore called 'printer'. When 'printer' 
executes it leaves its address on the stack. Typical usage is 


printer WAIT 

• • * ♦ 

using the printer 

printer AVAILABLE 


Some operations 


See AVAILABLE and SIGNAL and WAIT. 


setuser ( n - ) 

Set the current operating system user number to n. 


SIGN Unchanged 

SIGNAL { addr - ) 

In conjunction with WAIT, manage a counting semaphore. 
That is, assuming addr is the address of a semaphore, check 
whether there are any tasks waiting in the semaphore's queue 
and if so, transfer the first one to the tail of the active 
list but do not call PAUSE. Otherwise, increment the 
semaphore's count by one. SIGNAL is mainly useful in buffer 
management but is included since counting semaphores have 
other uses. For normal use, AVAILABLE is more appropriate. 


skip-until ( c - ) 

Advance the input pointer >IN until a character equal to c 
has been reached or the end of file is reached. In this 
context, a file is any of 

1. A line of input when BLK is zero and the input stream is 
not 2; 
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2. A complete ASCII file terminated by EOF when BLK is zero 
and the input stream is 2; 

3. A IK block of virtual memory when BLK is nonzero. 

In case 2 a new line is read into TIB and >IN is set to 0 if 
the end of a line is reached. 


skip-while ( c - ) 

Advance the output pointer until it points to a character 
other than c or until the end of file has been reached. A 
file is defined in the same way as for 'skip-until'. 


SMUDGE Unchanged 

SOFTWRAP ( - flag ) 

A constant that is TRUE except in Torch/BBC systems; it 
causes EMIT to call CR if there is insufficient space on the 
line for the character it is outputting, as measured by the 


contents 

of OUT compared with 

the value of C/L. 

SPl 

Unchanged 


SP@ 

Unchanged 


SPACE 

Unchanged 


SPACES 

Unchanged 


SPAN 

{-addr ) 

U 


A USER variable set by EXPECT to the number of characters 
it actually read. 


START ( addr ) 

Assuming addr is the address of the start of the user 
variable area of a task and assuming that task is in the 
stopped state, initialize it to start executing at the 
beginning of its code and append it to the tail of the active 
list. Then call PAUSE. If the task is not in a stopped state 
the effect is undefined (and often disastrous). 


STATE 


Unchanged 
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STD-ERROR ( n-) 

The standard xForth error routine which outputs, on stream 
0 and any other streams currently selected, an error message 
which has been read from disc if the low order bit of WARNING 
is set and a numeric error message otherwise. Then it sets 
OUTPUTS to 1 (i.e. selects output stream 0) and calls QUIT. 


STOP ( addr - ) 

Assuming addr is the address of the beginning of the user 
variable area of a task, and assuming the task is on the 
active list but is not executing, set its next instruction so 
that it will be removed from the active list and put in the 
stopped state as soon as it attempts to execute. 


STRING 

Unchanged 

SWAP 

Unchanged 

SYSADAPT 

Unchanged 

SYSFILE 

Unchanged 

SYSGEN 

Unchanged 

TAB 

( n-) 


If the contents of OUT are greater than or equal to n, do 
nothing. Otherwise, call SPACE often enough to make the value 
of OUT equal to n. 


tabsize ( - n ) 

A constant used (by the screen editor and by EXPECT) to 
determine the width of a tab stop. For example, EXPECT will 
convert a tab character one or more spaces so as to make the 
number of characters input equal to a multiple of tabsize. 


TASK: ( +++ ) 

Define a foreground task; that is, allocate space for 
#UVARS USER variables and initialize them according to the 
pattern in taskframe, but with the values offset correctly. 
Then perform various pre-initialization tasks, and finally 
switch to compilation mode. If is executed successfully 
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BrSkfoZ Snrli^i^r 

SckgroLd\isk ^ft t° allow "wOR^to brLllel "‘^inlike^I 


taskframe 


(-addr ) 


the'^sizes'^or I region which is used to determine 
tne sizes of the stacks, of the terminal input buffer and of 

fhA dictionary in a background task. The values are 
the size of the stack, the size of the return stack, the size 
of the terminal input buffer and the size of the dictiona^v 

K 1 Oa delivery the sizes of both stacks aro 
128 bytes, that of the TIB is 86 bytes and that of the 
dictionary is 192 bytes. Note that the PAD is 68 bytes above 
the dictionary pointer and is used widely, so do not make the 
dictionary area too small. On the other hand, it is often 
acceptable to make the size of the TIB zero since this is not 
normally used except during compilation. 


THEN 

TIB 

TOGGLE 

TRUE 

TYPE 

U$ 

U* 

U. 

U.R 

U/MOD 

U< 

UCHAR 

UNTIL 


Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 

Unchanged 


III clilU Ls^."" variables instead of those of 


addr ) 


t 7. Cl 
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Leave on the stack the address of the beginning of the user 

present task. B'or system use, but may 


it. 


UPDATE 

Unchanged 

USE 

Unchanged 

USER 

{ +++ ) 


Define a new USER variable, incrementing #UVARS so that the 
next defined USER variable will have a unique location. Note 

that COLD leaves space for 16 new user variables to be 
defined. 



VARIABLE 

VLIST 

VOC-LINK 

VOCABULARY 

WAIT 


Unchanged 
Unchanged • 
Unchanged 
Unchanged 

( addr — ) 


Assuming addr is the address of a semaphore, check whether 
Its count is nonzero. If this is the case, decrement the 
count and continue execution. Otherwise, remove the present 
task from the active list and transfer it to the tail of the 

semaphore's queue and transfer control to the new head of th^ 
active list. 


WARM Unchanged 

WARNING Unchanged 

WHERE (-) 


Invoke the screen editor 
position within the block g 

err>in.. 


with the cursor at the block and 
iven by the contents of ERRBLK and 


WHILE 

Unchanged 

WIDTH 

Unchanged 

WORD 

Unchanged 

wrap 

Unchanged 

XCURSOR 

Unchanged 

XEMIT 

( addr 


) 
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execution °"add5Lses^''’"which ^a^^ us^d^ 
o?derwS‘’jS*se''t''1:he°^ when ?h"e ^ow 

bit is saMt^!s^'x^SxT^^rrExlcu\TaU 


XEOF 


addr ) 


EXPECT“rrd“° a“fue"ren‘A° ""t 

input stream 2 is selected) “ ® “ ‘"■®- 


XERROR 


addr ) 


An execution variable containing the codp <-o Kxa r^aii^-v^ u 
ERROR, set to STD-ERROR on delivery. '=''' 


XINTERPRET 


addr ) 


variable containing the code called when 
INTERPREP executes, used by the metacompiler; lethal; tvoid 


XINTRPT 


addr ) 


An execution variable containing the code called when tho 
user interrupt key contained in INTRPT-KEY is read by ?PAUSE. 


XKEY 


(-addr ) 


Leave on the stack the start of a region containina 
execution addresses which are used by KEY The codp. 
corresponding to the lowest order set bit o'f INPUTS fs 

called. Conventionally, the low order bit corresponds to the 
operating system standard input. corresponds to the 


XLIMIT 


( — addr ) 


EIM??. “:rto°-6 r-'if delirry!"'"® 


I zn 
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XNUMBER 

Unchanged 

XOFF-CHAR 

Unchanged 

XOK 

Unchanged 

XOR 

Unchanged 

XPAGE 

Unchanged 

XPROMPT 

Unchanged 

XRUBOUT 

Unchanged 

XSIGNON 

Unchanged 

t 

Unchanged 

[,IVARIABLE 

Unchanged 

[COMPILE] 

Unchanged 

[IVARIABLE 

Unchanged 

] 

Unchanged 

"EMIT 

( c-) 



Strip the high order bit of c so it lies in the range 0 to 
127. If it is 127, discard it and call "?" while if it is 
32 to 126 inclusive, call EMIT for the value on the stack. If 
it is 13 (''M) call CR; if it is 12 (^L) call PAGE; if it is 10 
("J) ignore it; if it is 9 (''I) tab to the next multiple of 
tabsize. Otherwise output a caret " followed by the stack 
value plus 64, so that 3 is output as "C and so on. 



"TYPE ( $-) 

If $ has length zero, do nothing. Otherwise, call "EMIT 
for each of the characters in the string in turn. 


{ 

I 

} 


Unchanged 

Unchanged 

Unchanged 



I zo 


53 



